Add CI check to ensure that rustdoc JSON `FORMAT_VERSION` is correctly updated #142677

GuillaumeGomez · 2025-06-18T15:00:31Z

Follow-up of #142601.

Tested it locally with: BASE_COMMIT=1bb335244c311a07cee165c28c553c869e6f64a9 src/ci/docker/host-x86_64/mingw-check-1/validate-rustdoc-json-format-version-update.sh (where BASE_COMMIT value was the commit before I made a wrong change with the FORMAT_VERSION update).

This is a first version. I plan to send a follow-up to also ensure that FORMAT_VERSION is updated if any code change is done in rustdoc-json-types. For that I just need to check that a line not starting with / and not an empty line was updated. Fun times with grep ahead. :')

cc @aDotInTheVoid
r? @nnethercote

rustbot · 2025-06-18T15:00:36Z

nnethercote is not on the review rotation at the moment.
They may take a while to respond.

Kobzol · 2025-06-18T15:04:34Z

Could this be a tidy check instead? It's better to have these things in one centralized place in Rust, rather than scattered around in random bash scripts.

GuillaumeGomez · 2025-06-18T15:06:10Z

I guess? Didn't even realize that I could do the same in rust much more easily. ^^'

GuillaumeGomez · 2025-06-18T15:29:41Z

Moved it to tidy. I'll do the same with the other bash tidy check I added.

GuillaumeGomez · 2025-06-18T15:30:21Z

Oh also:

r? @Kobzol

Kobzol

I guess it could also work locally, but it's always a PITA to figure out a diff vs master, so this is fine. Could you please try to break the CI job in this PR to see if it works on PR CI?

src/tools/tidy/src/rustdoc_json.rs

rustbot · 2025-06-19T11:22:41Z

rustdoc-json-types is a public (although nightly-only) API. If possible, consider changing src/librustdoc/json/conversions.rs; otherwise, make sure you bump the FORMAT_VERSION constant.

cc @CraftSpider, @aDotInTheVoid, @Enselic, @obi1kenobi

Kobzol · 2025-06-19T12:02:35Z

2025-06-19T11:27:57.5354234Z [TIMING] core::build_steps::tool::Tidy { compiler: Compiler { stage: 0, host: x86_64-unknown-linux-gnu, forced_compiler: false }, target: x86_64-unknown-linux-gnu } -- 0.000
2025-06-19T11:27:57.5354975Z fmt check
2025-06-19T11:28:04.5397272Z fmt: checked 6074 files
2025-06-19T11:28:05.0397217Z tidy check
2025-06-19T11:28:24.2535092Z Running eslint on rustdoc JS files
2025-06-19T11:28:29.4054908Z tidy: Skipping binary file check, read-only filesystem
2025-06-19T11:28:36.0337263Z removing old virtual environment
2025-06-19T11:28:36.0359346Z creating virtual environment at '/checkout/obj/build/venv' using 'python3.10' and 'venv'
2025-06-19T11:28:36.0843019Z creating virtual environment at '/checkout/obj/build/venv' using 'python3.10' and 'virtualenv'
2025-06-19T11:28:37.6050421Z Requirement already satisfied: pip in ./build/venv/lib/python3.10/site-packages (25.1.1)
2025-06-19T11:28:38.8879878Z linting python files
2025-06-19T11:28:39.0477863Z All checks passed!
2025-06-19T11:28:39.0488259Z checking python file formatting
2025-06-19T11:28:39.1812151Z 28 files already formatted
2025-06-19T11:28:39.1822499Z checking C++ file formatting
2025-06-19T11:28:41.0313008Z x.py completions check

Looks like the check didn't run, hmm. Probably adding some logging before the return; statements would be useful, to figure out why. And also printing the output of git diff.

GuillaumeGomez · 2025-06-19T12:52:46Z

It's because BASE_COMMIT is not set in tidy. Changing that.

aDotInTheVoid

Conceptually this change makes sense and is good.

This is a first version. I plan to send a follow-up to also ensure that FORMAT_VERSION is updated if any code change is done in rustdoc-json-types. For that I just need to check that a line not starting with / and not an empty line was updated.

I worry that this could still have false positives. E.g. #142642 touches non-comments in src/rustdoc-json-types, but doesn't need to bump the FORMAT_VERSION

aDotInTheVoid · 2025-06-19T17:24:41Z

src/rustdoc-json-types/lib.rs

@@ -38,7 +38,7 @@ pub type FxHashMap<K, V> = HashMap<K, V>; // re-export for use in src/librustdoc
 // are deliberately not in a doc comment, because they need not be in public docs.)
 //
 // Latest feature: Pretty printing of inline attributes changed
-pub const FORMAT_VERSION: u32 = 48;
+pub const FORMAT_VERSION: u32 = 49;


This 48->49 change should be reverted before merging.

src/tools/tidy/src/main.rs

src/tools/tidy/src/rustdoc_json.rs

GuillaumeGomez · 2025-06-20T13:50:05Z

Check is failing as expected so removed the failing commit. Should be now.

Kobzol

Two nits, otherwise looks good.

Kobzol · 2025-06-20T13:56:13Z

src/tools/tidy/src/rustdoc_json.rs

+    ) {
+        Ok(Some(commit)) => commit,
+        Ok(None) => {
+            *bad = true;


Could you please only set *bad here and below on CI (if CiEnv::current() is CI)? For some users get_closest_upstream_commit might not return anything, e.g. if they have a shallow checkout. Yes, this is all sadly very annoying.. :D

I keep discovering new cases to handle 😆

Kobzol · 2025-06-20T13:57:01Z

src/tools/tidy/src/rustdoc_json.rs

+                *bad = true;
+                if latest_feature_comment_updated {
+                    eprintln!(
+                        "error: `Latest feature` comment was updated whereas `FORMAT_VERSION` wasn't"


Although people will probably be able to infer it, I think it would be nice if the error message contained the filename that should be fixed, otherwise the error can be quite opaque.

GuillaumeGomez · 2025-06-20T14:13:35Z

Applied your suggestions. Thanks a lot, learned a lot with this PR!

Only emit git errors if we are in CI environment

Kobzol · 2025-06-20T17:17:37Z

Yeah, there's really a lot to learn here 😆 Thanks!

@bors r+ rollup

bors · 2025-06-20T17:17:40Z

📌 Commit 0fc9507 has been approved by Kobzol

It is now in the queue for this repository.

Rollup of 8 pull requests Successful merges: - #142384 (Bringing `rustc_rayon_core` in tree as `rustc_thread_pool`) - #142476 (Insert parentheses around binary operation with attribute) - #142485 (Marks ADT live if it appears in pattern) - #142571 (Reason about borrowed classes in CopyProp.) - #142677 (Add CI check to ensure that rustdoc JSON `FORMAT_VERSION` is correctly updated) - #142716 (Adjust `with_generic_param_rib`.) - #142756 (Make `Clone` a `const_trait`) - #142765 (rustc_target: document public AbiMap-related fn and variants) r? `@ghost` `@rustbot` modify labels: rollup

Rollup merge of #142677 - GuillaumeGomez:check-format-version-update, r=Kobzol Add CI check to ensure that rustdoc JSON `FORMAT_VERSION` is correctly updated Follow-up of #142601. Tested it locally with: `BASE_COMMIT=1bb335244c311a07cee165c28c553c869e6f64a9 src/ci/docker/host-x86_64/mingw-check-1/validate-rustdoc-json-format-version-update.sh` (where `BASE_COMMIT` value was the commit before I made a wrong change with the `FORMAT_VERSION` update). This is a first version. I plan to send a follow-up to also ensure that `FORMAT_VERSION` is updated if any code change is done in `rustdoc-json-types`. For that I just need to check that a line not starting with `/` and not an empty line was updated. Fun times with `grep` ahead. :') cc `@aDotInTheVoid` r? `@nnethercote`

…version-update, r=Kobzol Check rustdoc-json-types FORMAT_VERSION is correctly updated Follow-up of rust-lang#142677. `@nnethercote` suggested that we should also ensure that the `FORMAT_VERSION` was only increased by 1 and we should check for it, this PR does it. cc `@aDotInTheVoid` r? ghost

…version-update, r=Kobzol Check rustdoc-json-types FORMAT_VERSION is correctly updated Follow-up of rust-lang#142677. ``@nnethercote`` suggested that we should also ensure that the `FORMAT_VERSION` was only increased by 1 and we should check for it, this PR does it. cc ``@aDotInTheVoid`` r? ghost

Rollup merge of #142875 - GuillaumeGomez:rustdoc-json-types-version-update, r=Kobzol Check rustdoc-json-types FORMAT_VERSION is correctly updated Follow-up of #142677. ``@nnethercote`` suggested that we should also ensure that the `FORMAT_VERSION` was only increased by 1 and we should check for it, this PR does it. cc ``@aDotInTheVoid`` r? ghost

…oval, r=Kobzol Move error code explanation removal check into tidy Follow-up of rust-lang#142677. This PR replaces a shell script with rust code. r? ghost

Rollup merge of #142827 - GuillaumeGomez:tidy-error-code-removal, r=Kobzol Move error code explanation removal check into tidy Follow-up of #142677. This PR replaces a shell script with rust code. r? ghost

…pdate, r=Kobzol Check rustdoc-json-types FORMAT_VERSION is correctly updated Follow-up of rust-lang/rust#142677. ``@nnethercote`` suggested that we should also ensure that the `FORMAT_VERSION` was only increased by 1 and we should check for it, this PR does it. cc ``@aDotInTheVoid`` r? ghost

rustbot assigned nnethercote Jun 18, 2025

rustbot added A-testsuite Area: The testsuite used to check the correctness of rustc S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-infra Relevant to the infrastructure team, which will review and decide on the PR/issue. labels Jun 18, 2025

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the check-format-version-update branch from 23e5243 to 5d9e058 Compare June 18, 2025 15:29

rustbot added A-tidy Area: The tidy tool T-bootstrap Relevant to the bootstrap subteam: Rust's build system (x.py and src/bootstrap) labels Jun 18, 2025

rustbot assigned Kobzol and unassigned nnethercote Jun 18, 2025

GuillaumeGomez mentioned this pull request Jun 18, 2025

Rewrite inline attribute parser to use new infrastructure and improve diagnostics for all parsed attributes #138165

Merged

Kobzol reviewed Jun 19, 2025

View reviewed changes

src/tools/tidy/src/rustdoc_json.rs Outdated Show resolved Hide resolved

GuillaumeGomez force-pushed the check-format-version-update branch from 5d9e058 to 43d18cf Compare June 19, 2025 11:22

rustbot added the A-rustdoc-json Area: Rustdoc JSON backend label Jun 19, 2025

GuillaumeGomez force-pushed the check-format-version-update branch from 76cea70 to 122cf96 Compare June 19, 2025 15:04

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the check-format-version-update branch from 122cf96 to c352ab5 Compare June 19, 2025 15:12

aDotInTheVoid reviewed Jun 19, 2025

View reviewed changes

Kobzol reviewed Jun 19, 2025

View reviewed changes

src/tools/tidy/src/main.rs Outdated Show resolved Hide resolved

GuillaumeGomez force-pushed the check-format-version-update branch from c352ab5 to 5c4daf1 Compare June 20, 2025 11:49

Kobzol reviewed Jun 20, 2025

View reviewed changes

src/tools/tidy/src/rustdoc_json.rs Show resolved Hide resolved

src/tools/tidy/src/rustdoc_json.rs Outdated Show resolved Hide resolved

GuillaumeGomez force-pushed the check-format-version-update branch from 5c4daf1 to 9cccf1e Compare June 20, 2025 12:50

This comment has been minimized.

Sign in to view

GuillaumeGomez added 2 commits June 20, 2025 15:49

Generate base commit in rustdoc_json tidy checks

bbe8a2a

Pass src_path to rustdoc_json tidy check

6367694

GuillaumeGomez force-pushed the check-format-version-update branch from aa1b8eb to 6367694 Compare June 20, 2025 13:49

Kobzol reviewed Jun 20, 2025

View reviewed changes

This comment has been minimized.

Sign in to view

Improve error message for rustdoc_json_types tidy check

0fc9507

Only emit git errors if we are in CI environment

GuillaumeGomez force-pushed the check-format-version-update branch from 989fd9d to 0fc9507 Compare June 20, 2025 14:22

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 20, 2025

tgross35 mentioned this pull request Jun 21, 2025

Rollup of 8 pull requests #142814

Merged

bors merged commit cd85b9d into rust-lang:master Jun 21, 2025
10 checks passed

rustbot added this to the 1.89.0 milestone Jun 21, 2025

GuillaumeGomez deleted the check-format-version-update branch June 21, 2025 13:22

This was referenced Jun 21, 2025

Move error code explanation removal check into tidy #142827

Merged

Check rustdoc-json-types FORMAT_VERSION is correctly updated #142875

Merged

GuillaumeGomez mentioned this pull request Jun 23, 2025

tidy: only run eslint on JS files if specified with "--extra-checks" #142851

Closed

GuillaumeGomez mentioned this pull request Jun 24, 2025

Port #[no_mangle] to new attribute parsing infrastructure #142823

Merged

Add CI check to ensure that rustdoc JSON FORMAT_VERSION is correctly updated #142677

Add CI check to ensure that rustdoc JSON FORMAT_VERSION is correctly updated #142677

Uh oh!

Conversation

GuillaumeGomez commented Jun 18, 2025

Uh oh!

rustbot commented Jun 18, 2025

Uh oh!

Kobzol commented Jun 18, 2025

Uh oh!

GuillaumeGomez commented Jun 18, 2025

Uh oh!

This comment has been minimized.

GuillaumeGomez commented Jun 18, 2025

Uh oh!

GuillaumeGomez commented Jun 18, 2025

Uh oh!

Kobzol left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rustbot commented Jun 19, 2025

Uh oh!

Kobzol commented Jun 19, 2025

Uh oh!

GuillaumeGomez commented Jun 19, 2025

Uh oh!

This comment has been minimized.

aDotInTheVoid left a comment

Choose a reason for hiding this comment

Uh oh!

aDotInTheVoid Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

GuillaumeGomez commented Jun 20, 2025

Uh oh!

Kobzol left a comment

Choose a reason for hiding this comment

Uh oh!

Kobzol Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

GuillaumeGomez Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

Kobzol Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

GuillaumeGomez Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

GuillaumeGomez commented Jun 20, 2025

Uh oh!

This comment has been minimized.

Kobzol commented Jun 20, 2025

Uh oh!

bors commented Jun 20, 2025

Uh oh!

Uh oh!

Uh oh!

Add CI check to ensure that rustdoc JSON `FORMAT_VERSION` is correctly updated #142677

Add CI check to ensure that rustdoc JSON `FORMAT_VERSION` is correctly updated #142677